<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
                      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <meta http-equiv="content-type" content="text/html; charset=UTF-8"/>
    <title>Zend_Dojo build layer support - Zend Framework Manual</title>

    <link href="../css/shCore.css" rel="stylesheet" type="text/css" />
    <link href="../css/shThemeDefault.css" rel="stylesheet" type="text/css" />
    <link href="../css/styles.css" media="all" rel="stylesheet" type="text/css" />
</head>
<body>
<h1>Zend Framework</h1>
<h2>Programmer's Reference Guide</h2>
<ul>
    <li><a href="../en/zend.dojo.build-layers.html">Inglês (English)</a></li>
    <li><a href="../pt-br/zend.dojo.build-layers.html">Português Brasileiro (Brazilian Portuguese)</a></li>
</ul>
<table width="100%">
    <tr valign="top">
        <td width="85%">
            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="zend.dojo.form.html">Dojo Form Elements and Decorators</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="zend.dojo.html">Zend_Dojo</a></span><br />
                        <span class="home"><a href="manual.html">Guia de Refer&ecirc;ncia do Programador</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="zend.dom.html">Zend_Dom</a></div>
                    </td>
                </tr>
            </table>
<hr />
<div id="zend.dojo.build-layers" class="section"><div class="info"><h1 class="title">Zend_Dojo build layer support</h1></div>
    

    <div class="section" id="zend.dojo.build-layers.introduction"><div class="info"><h1 class="title">Introduction</h1></div>
        

        <p class="para">
            Dojo build layers provide a clean path from development to
            production when using Dojo for your UI layer. In development, you
            can have load-on-demand, rapid application prototyping; a build
            layer takes all Dojo dependencies and compiles them to a single
            file, optionally stripping whitespace and comments, and performing
            code heuristics to allow further minification of variable names.
            Additionally, it can do <acronym class="acronym">CSS</acronym> minification.
        </p>

        <p class="para">
            In order to create a build layer, you would traditionally create a
            JavaScript file that has <strong class="command">dojo.require</strong> statements for
            each dependency, and optionally some additional code that might run
            when the script is loaded. As an example:
        </p>

        <pre class="programlisting brush: javascript">
dojo.provide(&quot;custom.main&quot;);

dojo.require(&quot;dijit.layout.TabContainer&quot;);
dojo.require(&quot;dijit.layout.ContentPane&quot;);
dojo.require(&quot;dijit.form.Form&quot;);
dojo.require(&quot;dijit.form.Button&quot;);
dojo.require(&quot;dijit.form.TextBox&quot;);
</pre>


        <p class="para">
            This script is generally referred to as a &quot;layer&quot; script.
        </p>

        <p class="para">
            Then, in your application&#039;s layout, you&#039;d instruct Dojo to load this
            module:
        </p>

        <pre class="programlisting brush: html">
&lt;html&gt;
&lt;head&gt;
    &lt;script type=&quot;text/javascript&quot; src=&quot;/js/dojo/dojo.js&quot;&gt;&lt;/script&gt;
    &lt;script type=&quot;text/javascript&quot;&gt;
        dojo.registerModulePath(&quot;custom&quot;, &quot;../custom/&quot;);
        dojo.require(&quot;custom.main&quot;);
    &lt;/script&gt;
</pre>


        <p class="para">
            If you use <span class="classname">Zend_Dojo</span> to do this, you&#039;d do the
            following:
        </p>

        <pre class="programlisting brush: php">
$view-&gt;dojo()-&gt;registerModulePath(&#039;custom&#039;, &#039;../custom/&#039;)
             -&gt;requireModule(&#039;custom.main&#039;);
</pre>


        <p class="para">
            But since <span class="classname">Zend_Dojo</span> aggregates your various
            <strong class="command">dojo.require</strong> statements, how do you create your layer
            script? You could open each page and view the generated
            <strong class="command">dojo.require</strong> statements, and cut and paste them into a
            layer script file manually.
        </p>

        <p class="para">
            However, a better solution exists: since
            <span class="classname">Zend_Dojo</span> aggregates this information
            already, you can simply pull that information and build your layer
            file. This is the purpose of
            <span class="classname">Zend_Dojo_BuildLayer</span>.
        </p>
    </div>

    <div class="section" id="zend.dojo.build-layers.usage"><div class="info"><h1 class="title">Generating Custom Module Layers with Zend_Dojo_BuildLayer</h1></div>
        

        <p class="para">
            At its simplest, you simply instantiate
            <span class="classname">Zend_Dojo_BuildLayer</span>, feed it the view object
            and the name of your custom module layer, and have it generate the
            content of the layer file; it is up to you to then write it to disk.
        </p>

        <p class="para">
            As an example, let&#039;s say you wanted to create the module layer
            &quot;<var class="filename">custom.main</var>&quot;. Assuming you follow the recommended project
            directory structure, and that you are storing your JavaScript files under
            <var class="filename">public/js/</var>, you could do the following:
        </p>

        <pre class="programlisting brush: php">
$build = new Zend_Dojo_BuildLayer(array(
    &#039;view&#039;      =&gt; $view,
    &#039;layerName&#039; =&gt; &#039;custom.main&#039;,
));

$layerContents = $build-&gt;generateLayerScript();
$filename      = APPLICATION_PATH . &#039;/../public/js/custom/main.js&#039;;
if (!file_exists(dirname($filename))) {
    mkdir(dirname($filename));
}
file_put_contents($filename, $layerContents);
</pre>


        <p class="para">
            When should you do the above? For it to work correctly, you need to
            do it after all view scripts and the layout have been rendered, to
            ensure that the  <span class="methodname">dojo()</span> helper is fully populated. One
            easy way to do so is using a front controller plugin, with a
             <span class="methodname">dispatchLoopShutdown()</span> hook:
        </p>

        <pre class="programlisting brush: php">
class App_Plugin_DojoLayer extends Zend_Controller_Plugin_Abstract
{
    public $layerScript = APPLICATION_PATH . &#039;/../public/js/custom/main.js&#039;;
    protected $_build;

    public function dispatchLoopShutdown()
    {
        if (!file_exists($this-&gt;layerScript)) {
            $this-&gt;generateDojoLayer();
        }
    }

    public function getBuild()
    {
        $viewRenderer = Zend_Controller_Action_HelperBroker::getStaticHelper(
            &#039;ViewRenderer&#039;
        );
        $viewRenderer-&gt;initView();
        if (null === $this-&gt;_build) {
            $this-&gt;_build = new Zend_Dojo_BuildLayer(array(
                &#039;view&#039;      =&gt; $viewRenderer-&gt;view,
                &#039;layerName&#039; =&gt; &#039;custom.main&#039;,
            ));
        }
        return $this-&gt;_build;
    }

    public function generateDojoLayer()
    {
        $build = $this-&gt;getBuild();
        $layerContents = $build-&gt;generateLayerScript();
        if (!file_exists(dirname($this-&gt;layerScript))) {
            mkdir(dirname($this-&gt;layerScript));
        }
        file_put_contents($this-&gt;layerScript, $layerContents);
    }
}
</pre>


        <blockquote class="note"><p><b class="note">Note</b>: <span class="info"><b>Do not generate the layer on every page</b><br /></span>
            

            <p class="para">
                It&#039;s tempting to generate the layer script on each and every
                page. However, this is resource intensive, as it must write to
                the disk on each page. Additionally, since the mtime of the file
                will keep changing, you will get no benefits of client-side
                caching. Write the file once.
            </p>
        </p></blockquote>

        <div class="section" id="zend.dojo.build-layers.usage.options"><div class="info"><h1 class="title">BuildLayer options</h1></div>
            

            <p class="para">
                The above functionality will suffice for most situations. For
                those needing more customization, a variety of options may be
                invoked.
            </p>

            <div class="section" id="zend.dojo.build-layers.usage.options.view"><div class="info"><h1 class="title">Setting the view object</h1></div>
                

                <p class="para">
                    While the view object may be passed during instantiation,
                    you may also pass it in to an instance via the
                     <span class="methodname">setView()</span> method:
                </p>

                <pre class="programlisting brush: php">
$build-&gt;setView($view);
</pre>

            </div>

            <div class="section" id="zend.dojo.build-layers.usage.options.layername"><div class="info"><h1 class="title">Setting the layer name</h1></div>
                

                <p class="para">
                    While the layer name may be passed during instantiation,
                    you may also pass it in to an instance via the
                     <span class="methodname">setLayerName()</span> method:
                </p>

                <pre class="programlisting brush: php">
$build-&gt;setLayerName(&quot;custom.main&quot;);
</pre>

            </div>

            <div class="section" id="zend.dojo.build-layers.usage.options.onload"><div class="info"><h1 class="title">Including onLoad events in the generated layer</h1></div>
                

                <p class="para">
                    <strong class="command">dojo.addOnLoad</strong> is a useful utility for
                    specifying actions that should trigger when the <acronym class="acronym">DOM</acronym> has
                    finished loading. The  <span class="methodname">dojo()</span> view helper can
                    create these statements via its
                     <span class="methodname">addOnLoad()</span> and
                     <span class="methodname">onLoadCapture()</span> methods. In some
                    cases, it makes sense to push these into your layer file
                    instead of rendering them via your view scripts.
                </p>

                <p class="para">
                    By default, these are not rendered; to enable them, pass the
                    <span class="property">consumeOnLoad</span> configuration key during
                    instantiation:
                </p>

                <pre class="programlisting brush: php">
$build = new Zend_Dojo_BuildLayer(array(
    &#039;view&#039;          =&gt; $view,
    &#039;layerName&#039;     =&gt; &#039;custom.main&#039;,
    &#039;consumeOnLoad&#039; =&gt; true,
));
</pre>


                <p class="para">
                    Alternately, you can use the
                     <span class="methodname">setConsumeOnLoad()</span> method after
                    instantiation:
                </p>

                <pre class="programlisting brush: php">
$build-&gt;setConsumeOnLoad(true);
</pre>

            </div>

            <div class="section" id="zend.dojo.build-layers.usage.options.javascript"><div class="info"><h1 class="title">Including captured JavaScript in the generated layer</h1></div>
                

                <p class="para">
                    The  <span class="methodname">dojo()</span> view helper includes methods for
                    capturing arbitrary JavaScript to include in the
                    &lt;script&gt; tag containing the various
                    <strong class="command">dojo.require</strong> and <strong class="command">dojo.addOnLoad</strong>
                    statements. This can be useful when creating default data
                    stores or globally scoped objects used throughout your
                    application.
                </p>

                <p class="para">
                    By default, these are not rendered; to enable them, pass the
                    <span class="property">consumeJavascript</span> configuration key during
                    instantiation:
                </p>

                <pre class="programlisting brush: php">
$build = new Zend_Dojo_BuildLayer(array(
    &#039;view&#039;              =&gt; $view,
    &#039;layerName&#039;         =&gt; &#039;custom.main&#039;,
    &#039;consumeJavascript&#039; =&gt; true,
));
</pre>


                <p class="para">
                    Alternately, you can use the
                     <span class="methodname">setConsumeJavascript()</span> method after
                    instantiation:
                </p>

                <pre class="programlisting brush: php">
$build-&gt;setConsumeJavascript(true);
</pre>

            </div>
        </div>
    </div>

    <div class="section" id="zend.dojo.build-layers.profiles"><div class="info"><h1 class="title">Generating Build Profiles with Zend_Dojo_BuildLayer</h1></div>
        

        <p class="para">
            One of the chief benefits of a Dojo module layer is that it
            facilitates the creation of a custom build.
            <span class="classname">Zend_Dojo_BuildLayer</span> has functionality for
            generate build profiles.
        </p>

        <p class="para">
            The simplest use case is to utilize the
             <span class="methodname">generateBuildProfile()</span> method and send the
            output to a file:
        </p>

        <pre class="programlisting brush: php">
$build = new Zend_Dojo_BuildLayer(array(
    &#039;view&#039;      =&gt; $view,
    &#039;layerName&#039; =&gt; &#039;custom.main&#039;,
));

$profile   = $build-&gt;generateBuildProfile();
$filename  = APPLICATION_PATH . &#039;/../misc/scripts/custom.profile.js&#039;;
file_put_contents($filename, $profile);
</pre>


        <p class="para">
            Just like generating layers, you may want to automate this via a
             <span class="methodname">dispatchLoopShutdown()</span> plugin hook; you
            could even simply modify the one shown for generating layers to read
            as follows:
        </p>

        <pre class="programlisting brush: php">
class App_Plugin_DojoLayer extends Zend_Controller_Plugin_Abstract
{
    public $layerScript  = APPLICATION_PATH
                         . &#039;/../public/js/custom/main.js&#039;;
    public $buildProfile = APPLICATION_PATH
                         . &#039;/../misc/scripts/custom.profile.js&#039;;
    protected $_build;

    public function dispatchLoopShutdown()
    {
        if (!file_exists($this-&gt;layerScript)) {
            $this-&gt;generateDojoLayer();
        }
        if (!file_exists($this-&gt;buildProfile)) {
            $this-&gt;generateBuildProfile();
        }
    }

    public function generateDojoLayer() { /* ... */ }

    public function generateBuildProfile()
    {
        $profile = $this-&gt;getBuild()-&gt;generateBuildProfile();
        file_put_contents($this-&gt;buildProfile, $profile);
    }

}
</pre>


        <p class="para">
            As noted, with module layers, you should only create the file once.
        </p>

        <div class="section" id="zend.dojo.build-layers.profiles.options"><div class="info"><h1 class="title">Build Profile options</h1></div>
            

            <p class="para">
                The above functionality will suffice for most situations. The
                only way to customize build profile generation is to provide
                additional build profile options to utilize.
            </p>

            <p class="para">
                As an example, you may want to specify what type of
                optimizations should be performed, whether or not to optimize
                <acronym class="acronym">CSS</acronym> files in the layer, whether or not to copy tests into the
                build, etc. For a listing of available options, you should read
                the <a href="http://docs.dojocampus.org/build/index" class="link external">&raquo; Dojo
                    Build documentation</a> and <a href="http://dojotoolkit.org/reference-guide/dojo/index.html#package-system" class="link external">&raquo; accompanying
                documentation</a>.
            </p>

            <p class="para">
                Setting these options is trivial: use the
                 <span class="methodname">addProfileOption()</span>,
                 <span class="methodname">addProfileOptions()</span>, or
                 <span class="methodname">setProfileOptions()</span> methods. The first
                method adds a single key and value option pair, the second will add
                several, and the third will overwrite any options with the list
                of key and value pairs provided.
            </p>

            <p class="para">
                By default, the following options are set:
            </p>

            <pre class="programlisting brush: javascript">
{
    action:        &quot;release&quot;,
    optimize:      &quot;shrinksafe&quot;,
    layerOptimize: &quot;shrinksafe&quot;,
    copyTests:     false,
    loader:        &quot;default&quot;,
    cssOptimize:   &quot;comments&quot;
}
</pre>


            <p class="para">
                You can pass in whatever key and value pairs you want; the Dojo
                build script will ignore those it does not understand.
            </p>

            <p class="para">
                As an example of setting options:
            </p>

            <pre class="programlisting brush: php">
// A single option:
$build-&gt;addProfileOption(&#039;version&#039;, &#039;zend-1.3.1&#039;);

// Several options:
$build-&gt;addProfileOptions(array(
    &#039;loader&#039;   =&gt; &#039;xdomain&#039;,
    &#039;optimize&#039; =&gt; &#039;packer&#039;,
));

// Or overwrite options:
$build-&gt;setProfileOptions(array(
    &#039;version&#039;  =&gt; &#039;custom-1.3.1&#039;,
    &#039;loader&#039;   =&gt; &#039;shrinksafe&#039;,
    &#039;optimize&#039; =&gt; &#039;shrinksafe&#039;,
));
</pre>

        </div>
    </div>
</div>
        <hr />

            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="zend.dojo.form.html">Dojo Form Elements and Decorators</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="zend.dojo.html">Zend_Dojo</a></span><br />
                        <span class="home"><a href="manual.html">Guia de Refer&ecirc;ncia do Programador</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="zend.dom.html">Zend_Dom</a></div>
                    </td>
                </tr>
            </table>
</td>
        <td style="font-size: smaller;" width="15%"> <style type="text/css">
#leftbar {
	float: left;
	width: 186px;
	padding: 5px;
	font-size: smaller;
}
ul.toc {
	margin: 0px 5px 5px 5px;
	padding: 0px;
}
ul.toc li {
	font-size: 85%;
	margin: 1px 0 1px 1px;
	padding: 1px 0 1px 11px;
	list-style-type: none;
	background-repeat: no-repeat;
	background-position: center left;
}
ul.toc li.header {
	font-size: 115%;
	padding: 5px 0px 5px 11px;
	border-bottom: 1px solid #cccccc;
	margin-bottom: 5px;
}
ul.toc li.active {
	font-weight: bold;
}
ul.toc li a {
	text-decoration: none;
}
ul.toc li a:hover {
	text-decoration: underline;
}
</style>
 <ul class="toc">
  <li class="header home"><a href="manual.html">Guia de Refer&ecirc;ncia do Programador</a></li>
  <li class="header up"><a href="manual.html">Guia de Refer&ecirc;ncia do Programador</a></li>
  <li class="header up"><a href="reference.html">Refer&ecirc;ncia do Zend Framework</a></li>
  <li class="header up"><a href="zend.dojo.html">Zend_Dojo</a></li>
  <li><a href="zend.dojo.introduction.html">Introduction</a></li>
  <li><a href="zend.dojo.data.html">Zend_Dojo_Data: dojo.data Envelopes</a></li>
  <li><a href="zend.dojo.view.html">Dojo View Helpers</a></li>
  <li><a href="zend.dojo.form.html">Dojo Form Elements and Decorators</a></li>
  <li class="active"><a href="zend.dojo.build-layers.html">Zend_Dojo build layer support</a></li>
 </ul>
 </td>
    </tr>
</table>

<script type="text/javascript" src="../js/shCore.js"></script>
<script type="text/javascript" src="../js/shAutoloader.js"></script>
<script type="text/javascript" src="../js/main.js"></script>

</body>
</html>